Frontend developer guide
===========================

This guide tries to give an overview over the frontend side of the project (html, css, javascript) regarding folders where things are stored, preprocessing ect.

-------------------------------------------
1. HTML
-------------------------------------------
HTML is generated server-side from templates (templates allow to put variables/lists/logic from Java into html). Uncompiled template code is not accessible from the client. There are two template engines which compile different types of templates and use a different template syntax:

1.1 Freemaker Java Template Engine
=> compiles .ftl files from folder: "src/main/webapp/WEB_INF/ftl"
=> See website with syntax, guides & docs: http://freemarker.org/
=> This engine is used, because the Java code can call this engine to compile html without having to send the html to the client. (This is not possible with the other templating engine, see 1.2).
=> Used to compile html for tasks dynamically (when needed) and send it to the client (by AJAX). The client javascript uses the html to build the task list on the page.
=> You can compile a template to a Java String by using the Java class "gmm.web.FtlRenderer".

1.2 Jasper 2 JSP Engine (Java Server Pages)
=> compiles .jsp files from folder: "src/main/webapp/WEB_INF/jsp"
=> compiles & uses .tag/.tagf files from folder: "src/main/webapp/WEB_INF/tags" when it compiles .jsp files. Files in the tags folder have the same basic syntax as .jsp files. tag(f) files serve as template for or part of jsp files.
=> This engine is part of the servlet container (tomcat server) and can only be used as part of a HTTP response (html) to the client. Sending it as AJAX/JSON is not possible. Because of this limitation, some template code has been converted to Freemarker templates (see 1.1).
=> You can compile a template (and send it as html page to the client) by returning the name of your JSP file in a Java Controller method (without file extension).
=> The file "all_template.tag" contains the basic html layout & menu used by every page.

-------------------------------------------
2. CSS
-------------------------------------------
CSS is generated by compiling SASS code. SASS is an "extension" for CSS.
=> compiles .scss files from folder: "src/main/frontend/sass" -----> to .css files in folder "src/main/webapp/resources/css/compiled"
=> SASS files (.scss) are very similar to real .css files, but allow things like variables, imports (include), nested selectors or functions/logic. It's possible to automatically minify the compiled .css files, too.
=> See website with syntax, guides & docs: http://sass-lang.com/
=> Files are compiled whenever you change a .scss file or start a complete maven build.
=> Basic folder structure:
- Files in "sass/all_template" folder belong to the html template file "all_template.tag".
- Files/folders in "sass/pages" folder belong to specific jsp pages with the same name.
- Files in "sass/shared" folder can be used by multiple pages.
- Files in "sass/include" folder contain variables (colours) & functions, and can be included multiple times. Any other file should not be included in the same page more than once, because then it would appear multiple times in compiled result.
- Files in the "sass" folder glue together all parts for every page using import statements only. They do not start with an underscore, because files not starting with underscore are top-level files compiled to real css files.

-------------------------------------------
3. Javascript (js)
-------------------------------------------
All custom js code is organized into modules (which can be imported in other modules). Global code is not allowed (only for not-yet-converted old js/html). The module syntax is from the not-yet-finished ES6 specification. Since browsers do not support modules, the ES 6 code is converted back to ES 5 code with the js library "Babel". Babel will not remove the modules, but convert them into common.js modules. From there, "Broserify" library will stuff the modules into one file per page for the browser.
=> Babel compiles ES 6 modules from folder: "src/main/frontend/javascript" ----> to folder "src/main/webapp/resources/javascript/compiled"
=> Any used libraries are not modules, so they are in "src/main/webapp/resources/javascript/lib". They are not packed into a single file by browserify and need to be referenced seperatly in html.
=> Global namespace can be accessed by using "global.<objectname>". Try to remove remaining global stuff.
=> Modules are compiled whenever you change an ES 6 file or start a complete maven build.
=> js can be validated by using JSHint, its settings file is at "src/main/frontend/.jshintrc". It's advised to exclude "src/main/frontend/node_modules" folder from validation

-------------------------------------------
4. Internationalization (i18n)
-------------------------------------------
=> i18n text ist stored in .properties files in folder "src/main/resources/i18n".
=> i18n text can be linked in all types of html templates using the keys from the properties files (for syntax examples see template source).
=> All i18n files should have their keys at the same line number for easy multi-file editing.
=> The language shown to the user is the users' chosen language (browser language settings).
=> i18n text cannot be used in CSS
=> i18n text can be used in js only manually currently (though that must change in future) by adding a keyname--->text mapping in a script tag in HTML templates.

-------------------------------------------
3. Other
-------------------------------------------
=> Only use HTTP request methods GET & POST because request bodies by other methods may be rejected by Tomcat.
=> Following HTTP specs strictly is not necessary, HTTP is used only because there is no better alternative that suites single-page-webapps, yet.
=> The build system used for JS/CSS building is "Gulp", running on node.js with npm. The file specifying npm dependencies (all needed libs for building) is "src/main/frontend/package.json". The gulp build file is "src/main/frontend/gulpfile.js". Node.js and npm will be downloaded and installed automatically as specified in maven build ("pom.xml") during the java build.
